IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/il_c/ilWarp.z/ilWarp

Text File | 2002-10-03 | 17.2 KB | 397 lines

iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



NNNNAAAAMMMMEEEE
     iiiillllWWWWaaaarrrrpppp - general 3D warp operations

IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
     ilWatchedObject

HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
     #include <il/ilCdefs.h>

CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The ilWarp class encapsulates general 3D coordinate transformations for
     use by ilWarpImg and subclasses thereof.  A particular warp is defined by
     overriding the eeeevvvvaaaallll() virtual.  Several other virtuals can be overridden
     to enable more efficient batch evaluation, inversion, composition, and so
     forth.

     The ilWarp class contains one pure virtual method, ccccooooppppyyyy(), so it is not
     possible to construct an ilWarp object, and any concrete derived class
     must implement the copy virtual.  The ilWarpImg operator relies on the
     copy method to maintain an internal copy of a user-supplied warp.

     ilWarp is derived from ilWatchedObject.  This makes it possible to set a
     "dynamic" warp object on an ilWarpImg --- one that is not copied, but
     instead "watched" for any changes.  When the warp changes, the ilWarpImg
     responds appropriately.  This implies that any class that is derived from
     ilWarp must trigger the appropriate notification whenever it is changed.
     In particular the non-const virtual methods iiiiddddeeeennnnttttiiiittttyyyy(), iiiinnnnvvvveeeerrrrtttt(),
     ccccoooommmmppppoooosssseeee(), and iiiinnnnffffeeeerrrr() should call the protected method wwwwaaaarrrrppppCCCChhhhaaaannnnggggeeeedddd().
     (However, if any of these methods fails and leaves the warp unchanged the
     wwwwaaaarrrrppppCCCChhhhaaaannnnggggeeeedddd() method should not be called.)

     ilWarp provides several alternative means to evaluate the warp that it
     specifies.  The principal one is eeeevvvvaaaallll() which must be defined by a
     derived class.  The others are xxxx(), yyyy(), and zzzz(), which evaluate the
     components of the warp, ddddxxxx(), ddddyyyy(), and ddddzzzz(), which evaluate the Jacobian
     of the warp,

CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
     CCCCooooppppyyyyiiiinnnngggg

          virtual ilWarp* ilWarpCopy(ilWarp *obj)

     WWWWaaaarrrrpppp eeeevvvvaaaalllluuuuaaaattttiiiioooonnnn mmmmeeeetttthhhhooooddddssss

          virtual void ilWarpEval3D(ilWarp *obj, float* x, float* y,
                                    float* z, float u, float v,
                                    float w)
          void ilWarpEval(ilWarp *obj, float* x, float* y, float u,
                          float v)
          virtual float ilWarpX(ilWarp *obj, float u, float v, float w)
          virtual float ilWarpY(ilWarp *obj, float u, float v, float w)
          virtual float ilWarpZ(ilWarp *obj, float u, float v, float w)



                                                                        PPPPaaaaggggeeee 1111






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          virtual void ilWarpDx(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)
          virtual void ilWarpDy(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)
          virtual void ilWarpDz(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)
          virtual ilStatus ilWarpGetBBox(ilWarp *obj, iflXYZfloat* min,
                                         iflXYZfloat* max, int su,
                                         int sv, int sw, int nu,
                                         int nv, int nw)
          ilStatus ilWarpGetBBox2D(ilWarp *obj, iflXYZfloat* min,
                                   iflXYZfloat* max, int su, int sv,
                                   int nu, int nv)
          virtual void ilWarpEvalVector(ilWarp *obj, float upos,
                                        float vpos, float ustep,
                                        iflXYfloat *addrs, int count,
                                        float wpos)
          void ilWarpFindRoot(ilWarp *obj, const iflXYZfloat* xy,
                              iflXYZfloat* uv, int tries, float xyzTol,
                              float uvwTol)

     WWWWaaaarrrrpppp mmmmaaaannnniiiippppuuuullllaaaattttiiiioooonnnn

          virtual void ilWarpIdentity(ilWarp *obj)
          virtual ilStatus ilWarpInvert(ilWarp *obj, ilWarpQuality quality,
                                        float ulo, float uhi,
                                        float vlo, float vhi,
                                        float wlo, float whi)
          virtual ilStatus ilWarpCompose(ilWarp *obj, const ilWarp* other,
                                         ilWarpQuality quality)
          virtual ilStatus ilWarpInfer(ilWarp *obj,
                                       ilTiePointList* tiePoints,
                                       ilWarpQuality quality)
          virtual int ilWarpMinimumNumberOfTies(ilWarp *obj)

     AAAAlllltttteeeerrrraaaattttiiiioooonnnn ccccaaaallllllllbbbbaaaacccckkkk mmmmeeeetttthhhhooooddddssss

FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
     ccccoooommmmppppoooosssseeee(((())))

          virtual ilStatus ilWarpCompose(ilWarp *obj, const ilWarp* other,
                                         ilWarpQuality quality)


          Compose this warp with another. This object is updated to reflect
          the composite transformation equivalent to applying
          (*this)(other(p)).  The default implementation returns ilFAILED.  If
          quality is ilWarpExact, then the method should return ilOKAY only if
          the precise composition can be computed.  Otherwise it should return
          ilFAILED.  If quality is ilWarpBest, then the method can return
          ilAPPROXIMATE if only an approximate composition can be computed.
          If the composition operation fails, then this object should be



                                                                        PPPPaaaaggggeeee 2222






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          unmodified.

     ccccooooppppyyyy(((())))

          virtual ilWarp* ilWarpCopy(ilWarp *obj)


          This is a pure virtual method that allocates a duplicate of the warp
          object.  It is used by ilWarpImg to maintain an internal copy of the
          warp passed by ilWarpImg::setWarp().

     ddddxxxx(((())))

          virtual void ilWarpDx(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)


          Evaluate the partial derivatives (dx/du,dy/du,dz/du) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     ddddyyyy(((())))

          virtual void ilWarpDy(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)


          Evaluate the partial derivatives (dx/dv,dy/dv,dz/dv) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     ddddzzzz(((())))

          virtual void ilWarpDz(ilWarp *obj, float* x, float* y,
                                float* z, float u, float v, float w)


          Evaluate the partial derivatives (dx/dw,dy/dw,dz/dw) of the warp
          function at the point (u,v,w).  The default implementation returns
          zeros.

     eeeevvvvaaaallll(((())))

          virtual void ilWarpEval3D(ilWarp *obj, float* x, float* y,
                                    float* z, float u, float v,
                                    float w)


          void ilWarpEval(ilWarp *obj, float* x, float* y, float u,
                          float v)





                                                                        PPPPaaaaggggeeee 3333






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          This is a convenience method to evaluate all three coordinates of
          the transformation and return the result in a structure.  The 2D
          version assumes that w = 0.

     eeeevvvvaaaallllVVVVeeeeccccttttoooorrrr(((())))

          virtual void ilWarpEvalVector(ilWarp *obj, float upos,
                                        float vpos, float ustep,
                                        iflXYfloat *addrs, int count,
                                        float wpos)


          Perform the equivalent of

          for (int i=0; i<count; i++) {
              float z;
              eval(addrs[i].x, addrs[i].y, z, upos+ustep*i, vpos, wpos);
          }


          for use by the ilWarpImg address generation function.  This function
          should be optimized as much as possible by derived classes in order
          to achieve good ilWarpImg performance.

     ffffiiiinnnnddddRRRRooooooootttt(((())))

          void ilWarpFindRoot(ilWarp *obj, const iflXYZfloat* xyz,
                              iflXYZfloat* uvw, int tries, float xyzTol,
                              float uvwTol)


          Search numerically for the solution to

              xyz = warp(uvw).


          The search terminates when one of the following conditions is met:
          (1) the number of iterations exceeds _t_r_i_e_s, (2) the difference
          between successive approximations is <= _x_y_z_T_o_l, or (3) the
          difference between (_x_y_z) and warp(_u_v_w) is <= _u_v_w_T_o_l.

     ggggeeeettttBBBBBBBBooooxxxx(((())))

          ilStatus ilWarpGetBBox2D(ilWarp *obj, iflXYZfloat* min,
                                   iflXYZfloat* max, int su, int sv,
                                   int nu, int nv)
          virtual ilStatus ilWarpGetBBox(ilWarp *obj, iflXYZfloat* min,
                                         iflXYZfloat* max, int su,
                                         int sv, int sw, int nu,
                                         int nv, int nw)





                                                                        PPPPaaaaggggeeee 4444






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



          Return the bounding box of the mapped rectangle with corners
          (su,sv,sw) and (su+nu,sv+nv,sw+nw).  The lower-left and upper-right
          vertices of the box are returned in the min and max structures,
          respectively.  The default implementation is by sampling the
          boundary of the input rectangle at a fixed granularity and computing
          the bounding box of the mapped set of sample points.  It returns
          ilOKAY if the computation is successful and ilFAILED otherwise.  The
          2D version assumes sw == 0 and nw == 1.

     iiiiddddeeeennnnttttiiiittttyyyy(((())))

          virtual void ilWarpIdentity(ilWarp *obj)


          Sets the warp to the identity function.  The default implementation
          does nothing.

     iiiinnnnffffeeeerrrr(((())))

          virtual ilStatus ilWarpInfer(ilWarp *obj,
                                       ilTiePointList* tiePoints,
                                       ilWarpQuality quality)


          Infer the warp from a set of point correspondences in the input and
          output spaces.  See ccccoooommmmppppoooosssseeee() for the interpretation of the quality
          argument.  The default implementation returns ilFAILED.  This method
          must be defined by any subclass that will be used by ilTieWarpImg.

     iiiinnnnvvvveeeerrrrtttt(((())))

          virtual ilStatus ilWarpInvert(ilWarp *obj, ilWarpQuality quality,
                                        float ulo, float uhi,
                                        float vlo, float vhi,
                                        float wlo, float whi)


          Invert the warp over the domain specified by the rectangle
          (ulo,vlo,wlo) to (uhi,vhi,whi).  The accuracy of the inverse outside
          this rectangle is undefined.  See ccccoooommmmppppoooosssseeee() for the interpretation
          of the quality argument.  The default implementation uses iiiinnnnffffeeeerrrr() to
          guess the inverse via a set of tie points.

     mmmmiiiinnnniiiimmmmuuuummmmNNNNuuuummmmbbbbeeeerrrrOOOOffffTTTTiiiieeeessss(((())))

          virtual int ilWarpMinimumNumberOfTies(ilWarp *obj)


          Return the minimum number of tie points necessary to infer the warp.
          The default implementation returns INT_MAX.





                                                                        PPPPaaaaggggeeee 5555






iiiillllWWWWaaaarrrrpppp((((3333))))          IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll          iiiillllWWWWaaaarrrrpppp((((3333))))



     xxxx(((())))

          virtual float ilWarpX(ilWarp *obj, float u, float v, float w)


          Evaluate the x component of the warp function at a point.  The
          default implementation is to return u.  This virtual should be
          overridden by any derived class that transforms the x component.

     yyyy(((())))

          virtual float ilWarpY(ilWarp *obj, float u, float v, float w)


          Evaluate the y component of the warp function at a point.  The
          default implementation is to return v.  This virtual should be
          overridden by any derived class that transforms the y component.

     zzzz(((())))

          virtual float ilWarpZ(ilWarp *obj, float u, float v, float w)


          Evaluate the z component of the warp function at a point.  The
          default implementation is to return w.  This virtual should be
          overridden by any derived class that transforms the z component.

IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
   IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt
     addWatchCallback(), doWatchCallbacks(), removeWatchCallback()


SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ilWarpImg, ilPolyWarp, ilAffineWarp, ilPolyDef, ilTieWarpImg





















                                                                        PPPPaaaaggggeeee 6666